Skip to content

gh-58752: Doc: Clarify sys.path[0] behavior for symbolic and hard links#142160

Open
bobzinin wants to merge 1 commit into
python:mainfrom
bobzinin:document-symlink-behavior
Open

gh-58752: Doc: Clarify sys.path[0] behavior for symbolic and hard links#142160
bobzinin wants to merge 1 commit into
python:mainfrom
bobzinin:document-symlink-behavior

Conversation

@bobzinin

@bobzinin bobzinin commented Dec 1, 2025

Copy link
Copy Markdown

Improve documentation of how Python sets sys.path[0] when the script is accessed via different link types:

  • On Unix-like systems, symbolic links are resolved to target directory
  • Hard links and Windows file links use the link's own directory

Fixes #58752


📚 Documentation preview 📚: https://cpython-previews--142160.org.readthedocs.build/

Comment thread Doc/using/cmdline.rst Outdated
Comment on lines +162 to +164
If the script name refers to a link, the behavior depends on the link type and operating system.
On Unix-like systems, symbolic links are resolved to the target file's directory when added to :data:`sys.path`.
Hard links use the link's own directory. On Windows, both hard links and symbolic links use the link's own directory.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please wrap lines to 79 characters.

Improve documentation of how Python sets sys.path[0] when the script
is accessed via different link types:
- On Unix-like systems, symbolic links are resolved to target directory
- Hard links and Windows file links use the link's own directory

Fixes python#58752
@bobzinin bobzinin force-pushed the document-symlink-behavior branch from 90033d8 to b3035ff Compare December 1, 2025 20:30
@github-actions

github-actions Bot commented May 3, 2026

Copy link
Copy Markdown

This PR is stale because it has been open for 30 days with no activity.

@github-actions github-actions Bot added the stale Stale PR or inactive for long period of time. label May 3, 2026
@serhiy-storchaka serhiy-storchaka requested a review from ncoghlan June 2, 2026 18:09

@serhiy-storchaka serhiy-storchaka left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not think we should mention hard links. They are indistinguishable from "normal" files or directories on Posix.

Also, the proposed text looks unclear to me.

@github-actions github-actions Bot removed the stale Stale PR or inactive for long period of time. label Jun 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

Document behaviour of python when launched on symlink to a script

3 participants